Get Customer Offer Details [V3]

This API is used to retrieve the full data of a selected customer offer. The customer can retrieve the data of an offer it created itself for its sub-accounts or an offer assigned to it by its Parent account.

HTTP URL

 

GET

/api/v3/customer/{id}/offer/{id}

Eligibility

The Requester is eligible to request information on offers that it created and that are available for attachment to sub-customers or offers assigned to it by its Parent account.

API Request

This API has no request structure.

API Reposnse

Response Structure

Parameter

Type

M/O/CM

Description

errorCode

String

O

Failure code.

errorMessage

String

O

Failure message.

content

Object

O

Array of main response body object displayed when an API call was successful. For a failure, it will be empty.

pageable

Object

O

Paging information object displayed when an API call was successful. For a failure, it will be empty.

Content data objects

Element

Type

M/O/CM

Description

id

UUID

M

Product Offering ID

name

String

M

Offer name

description

String

O

Offer description

class

String

M

Offer classification.

ENUM: SELL_PLAN, BUY_PLAN

type

String

M

Individual offer type.

ENUM: RATE, MONEY, USAGE, POOL

cost

Decimal

M

Cost of the offer. May contain a decimal value.

If no cost is applied, send 0 (zero).

POOL plan type definitions:

FIXED: Cost of the offer, as like all other offer types

ACCUMULATIVE: Cost that is added with every added subscriber

currency

String

M

Cost currency, such as USD, GBP, EUR.

creationTime

DateTime

M

Offer creation timestamp

renewalInterval

String

M

Renewal period interval.

ENUM valid values: DAILY, WEEKLY, MONTHLY, QUARTERLY, SEMI_ANNUALLY, ANNUALLY, ONE_TIME

renewalIntervalMethod

String

CM

Determines how to set the renewal day.

ENUM valid values:

FIRST_DAY: Renewal day will be the first day of the renewal interval, for example, first of the month per MONTHLY interval.

SELF_DEFINED: Renewal day will be the day defined by the user, for example, 10th of the month per MONTHLY interval.

PLAN_ALLOCATION: Renewal day will be set based on the actual plan allocation (attachment) day.

Empty for ONE_TIME renewal interval

renewalIntervalDay

Numeric

CM

Determines the renewal day of the selected period.

ENUM valid values:

DAILY: N/A

WEEKLY: 1–7

MONTHLY: 1–28

QUARTERLY: 1–90

SEMI_ANNUALLY: 1–180

ANNUALLY: 1–365

ONE_TIME: N/A

Populated only if SELF_DEFINED or FIRST_DAY has been set for the renewalIntervalMethod attribute.

expirationType

String

O

Determines how to set the expiration date.

ENUM valid values:

FIXED: Fixed, predefined expiration date.

RELATIVE_ATTACHED: Time duration from the moment the plan was attached to the subscriber (SIM), for example, 10 days.

RELATIVE_FIRST_USE: Time duration from the time the plan was first used by the subscriber, for example 10 days.

If not sent, the plan will not expire at all.

expirationDate

Date

CM

Determines the requested date as per the selected expirationType.

Populated only if the expirationType parameter has been set to FIXED.

Empty for other expirationType settings or no expiration type.

expirationUnit

String

CM

Determines the time unit that should be used for expiration calculation.

ENUM valid values: DAY, WEEK, MONTH, YEAR

Empty if the selected expirationType is FIXED or no expiration type.

expirationValue

Numeric

CM

Determines the requested time value as per the selected expirationUnit.

Empty if the selected expirationType is FIXED or no expiration type.

isProrated

Boolean

M

Plan proration.

True = Proration will be calculated when attaching this plan

False = There is no proration

A Pool plan is always False.

money

Object

CM

Money type object.

Populated when a MONEY offer type is returned

Empty if a RATE, USAGE or POOL offer type is returned

money data objects.

rate

Object

CM

Rate type object.

Populated whena RATE offer type is returned

Empty if a USAGE, MONEY or POOL offer type is returned

rate data objects.

usage

Object

CM

Usage type object.

Populated when a USAGE offer type is returned

Empty if a RATE, MONEY or POOL offer type is returned

usage data objects.

pool

Object

CM

Pool plan type object.

Populated when a POOL offer type is returned

Empty if any other offer type is returned (USAGE, RATE, MONEY).

pool data objects.

eligibleSubAccountIds

UUID

CM

[Future Feature]

Array of sub account UUIDs. Specified sub account(s) are the accounts that are eligible to use this plan.

POOL Plan type: A single sub-account is always displayed

RATE, MONEY, USAGE types: Can be empty or filled with a single sub-account or multiple sub-accounts

availabilityZone

Object

O

Array of availability zones object that are assigned to this plan.

Empty array means that the plan is available in any zone.

availability zone data objects.

linkedOffers

Object

O

Array of offer(s) object linked to this offer. The order of the instances in the array determines their priority for charging.

An Empty array means that the created offer has no linked offers.

linked offers data objects.

Money data objects

Element

Type

M/O/CM

Description

activationType

String

M

Displays plan activation behavior.

Valid values:

REGULAR

FIRSTEVENT_PERIODIC

FIRST_EVENT_NON_PERIODIC

Rate data objects

Element

Type

M/O/CM

Description

type

String

M

Rate offer type.

ENUM valid values: ACCOUNT, PLAN_FIXED, PLAN_CUSTOMIZED

dataLimit

Decimal

O

Displays the maximal allowed DATA usage consumption.

dataLimitUnitType

String

CM

Data limit unit type. Valid values: KB, MB, GB

Populated when data limit exists.

smsLimit

Decimal

O

Displays the maximal allowed SMS usage consumption. Unit counting is always a ‘unit’.

price

Object

O

Array of plan price object.

Populated if the type element is PLAN_FIXED or PLAN_CUSTOMIZED.

Empty if type is ‘ACCOUNT.

price data objects

Price data objects

Element

Type

M/O/CM

Description

serviceType

String

M

Type of usage.

ENUM valid values: DATA, SMS

unitType

String

CM

Usage unit type.

ENUM valid values: KB, MB, GB

Populated when serviceType is set to DATA.

Empty when serviceType is set to SMS.

type

String

M

Price type.

ENUM valid values: REGULAR, BLOCK, PASS

price

Decimal

CM

Price per unit consumption

Data: Price per unit (KB/MB/GB) consumption

SMS: Price per SMS consumption

Mandatory when type is set to REGULAR

currency

String

CM

Currency, such as USD, GBP, EUR

Mandatory when type is set to REGULAR

countryCode

String

M

ISO alpha-3 Country Code

network

Object

M

Mobile Network object

(Mobile) Network data objects

(Mobile) Network data objects

Element

Type

M/O/CM

Description

plmn

String

M

Public Land Mobile Network.

MCCMNC representation

mcc

String

M

Mobile Country Code (MCC)

mnc

String

M

Mobile Network Code (MNC)

Usage data objects

Element

Type

M/O/CM

Description

activationType

String

M

Displays plan activation behavior.

Valid values:

REGULAR

FIRSTEVENT_PERIODIC

FIRST_EVENT_NON_PERIODIC

usageType

Object

M

Array of usage types object.

Usage Type data objects

Usage Type data objects

Element

Type

M/O/CM

Description

type

String

M

Type of the usage. Valid values: DATA, SMS

value

Decimal

M

Overall allowance value for regular offer or for FIXED-type Pool Plan.

Allowance value per every added subscriber for ACCUMULATIVE-type Pool Plan.

Data consumption for DATA type.

Unit counting for SMS type.

unitType

String

CM

Usage unit type = DATA

Valid values: KB, MB, GB.

Populated when usage type is set to DATA.

Pool data objects

Element

Type

M/O/CM

Description

subAccount

String

M

Name of the sub account for which the Pool Plan was created.

type

String

M

Pool plan type. Valid values: FIXED, ACCUMULATIVE

activationType

String

M

Defines pool plan activation behavior.

Valid values:

REGULAR

FIRSTEVENT_PERIODIC

FIRST_EVENT_NON_PERIODIC

poolusageType

Object

M

Array of (pool) usage types object.

Pool Usage Type data objects

Pool Usage Type data objects

Element

Type

M/O/CM

Description

type

String

M

Type of the usage.

ENUM valid values: DATA, SMS

value

Decimal

M

Allowance value.

Data consumption for DATA type.

Unit counting for SMS type.

unitType

String

CM

Usage unit type = DATA

ENUM valid values: KB, MB, GB

Mandatory for DATA usage type. Empty for SMS usage type.

Ignored if populated for SMS usage type.

limitValue

Decimal

O

Defines usage limit value.

Data consumption for DATA type.

Unit counting for SMS type.

limitUnitType

String

CM

Limit unit type = DATA

ENUM valid values: KB, MB, GB

Mandatory when setting the limit for DATA usage. Empty for SMS usage type.

Ignored if populated for SMS usage type.

Availability Zone data objects

Element

Type

M/O/CM

Description

id

UUID

M

Universal unique ID of the customer's availability zones.

name

String

M

Customer's availability zone name.

Linked Offers data objects

Element

Type

M/O/CM

Description

id

UUID

M

Universal unique ID of the offer to link to this offer.

isPinned

Boolean

O

[Future Feature]

Denotes whether or not the linked offer can be removed from the parent offer.

True = Linked offer is fixed and cannot be removed.

False = Linked offer is not fixed and can be removed

Pageable data objects

Element

Type

M/O/CM

Description

page

Numeric

M

Page number

size

Numeric

M

Page size. Number of requested elements per page

totalPages

Numeric

M

Total amount of available pages per requested page size

totalElements

Numeric

M

Total amount of retrieved elements

Error Codes

In addition to the general success and failure codes, the following error codes are possible.

Code

Message

GLOBAL_1001

Service unavailable. Please try again

CUSTOMER_1002

Customer does not exist

CUSTOMER_1006

Failed to retrieve customer details

Examples

Request Body

Copy 
{
}

Response Body: Regular Plan (Money) Success ACK

Copy 
{
  "errorCode": "",
  "errorMessage": "",
  "content": [
    {
      "id": "e7fcef24-5c03-41dd-9e33-995b7d6f47a7",
      "name": "roaming",
      "description": "roaming bundle",
      "class": "SELL_PLAN",
      "type": "MONEY",
      "cost": 20.5,
      "currency": "USD",
      "creationTime": "2020-07-01T00:00:00.977Z",

      "renewalInterval": "MONTHLY",
      "renewalIntervalMethod": "FIRST_DAY",
      "renewalIntervalDay": "",
      "expirationType": "FIXED",
      "expirationDate": "13092023",
      "expirationUnit": "",
      "expirationValue": "",
      "isProrated": true,
      "availabilityZone": [
        {
          "id": "1b15048b-1ed4-4d34-a074-c7e26520e12a",
          "name": "North America 05"
        }
      ],
      "money": [
        {
          "activationType": "REGULAR"
        }
      ],
      "eligibleSubAccountIds": [
        "ee74dca6-8e7f-4b85-a42b-13860913b3b1",
        "ff74dca6-8e7f-4b85-a42b-13860913b370"
      ],
      "linkedOffers": [
        {
          "id": "ee74dca6-8e7f-4b85-a42b-13860913b3b1",
          "isPinned": true
        },
        {
          "id": "ff74dca6-8e7f-4b85-a42b-13860913b370",
          "isPinned": true
        }
      ]
    }
  ],
  "pageable": {
    "page": 1,
    "size": 10,
    "totalPages": 1,
    "totalElements": 2
  }
}

Response Body: Pool Plan Success ACK

Copy 
{
  "errorCode": "",
  "errorMessage": "",
  "content": [
    {
      "id": "e7fcef24-5c03-41dd-9e33-995b7d6f47a7",
      "name": "Family 50GB+",
      "description": "Family bundle",
      "class": "SELL_PLAN",
      "type": "POOL",
      "cost": 15,
      "currency": "USD",
      "creationTime": "2020-07-01T00:00:00.977Z",
      "renewalInterval": "MONTHLY",
      "renewalIntervalMethod": "FIRST_DAY",
      "renewalIntervalDay": "",
      "expirationType": "FIXED",
      "expirationDate": "13092023",
      "expirationUnit": "",
      "expirationValue": "",
      "isProrated": false,
      "pool": [
        {
          "subAccount": "Gualas LTD.",
          "type": "FIXED",
          "activationType": "REGULAR",
          "poolUsageType": [
            {
              "type": "DATA",
              "value": 50,
              "unitType": "GB",
              "limitValue": 20,
              "limitUnitType": "GB"
            },
            {
              "type": "SMS",
              "value": 100,
              "unitType": "",
              "limitValue": 10,
              "limitUnitType": ""
            }
          ]
        }
      ],
      "eligibleSubAccountIds": [
        "b8fcef24-8a03-41ed-9e43-195b7d6d42a6"
      ],
      "availabilityZone": [
        {
          "id": "1b15048b-1ed4-4d34-a074-c7e26520e12a",
          "name": "North America 05"
        }
      ],
      "linkedOffers": [
        {
          "id": "ee74dca6-8e7f-4b85-a42b-13860913b3b1",
          "isPinned": true
        },
        {
          "id": "ff74dca6-8e7f-4b85-a42b-13860913b370",
          "isPinned": true
        }
      ]
    }
  ],
  "pageable": {
    "page": 1,
    "size": 10,
    "totalPages": 1,
    "totalElements": 2
  }
}

Response Body: Failure NAK

Copy 
{
  "errorCode": "GLOBAL_1001",
  "errorMessage": "Service unavailable. Please try again",
  "content": "",
  "pageable": ""
}